home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW cawf 4.0.9 / cawf.1 < prev    next >
Encoding:
Text File  |  1995-12-01  |  22.9 KB  |  918 lines  |  [TEXT/ttxt]

  1. .\"    manual page for cawf(1)
  2. .\"
  3. .\"
  4. .\"    Copyright (c) 1991 Purdue University Research Foundation,
  5. .\"    West Lafayette, Indiana 47907.  All rights reserved.
  6. .\"
  7. .\"    Written by Victor A. Abell <abe@cc.purdue.edu>,  Purdue
  8. .\"    University Computing Center.  Not derived from licensed software;
  9. .\"    derived from awf(1) by Henry Spencer of the University of Toronto.
  10. .\"
  11. .\"    Permission is granted to anyone to use this software for any
  12. .\"    purpose on any computer system, and to alter it and redistribute
  13. .\"    it freely, subject to the following restrictions:
  14. .\"
  15. .\"    1. The author is not responsible for any consequences of use of
  16. .\"       this software, even if they arise from flaws in it.
  17. .\"
  18. .\"    2. The origin of this software must not be misrepresented, either
  19. .\"       by explicit claim or by omission.  Credits must appear in the
  20. .\"       documentation.
  21. .\"
  22. .\"    3. Altered versions must be plainly marked as such, and must not
  23. .\"       be misrepresented as being the original software.  Credits must
  24. .\"       appear in the documentation.
  25. .\"
  26. .\"    4. This notice may not be removed or altered.
  27. .\"
  28. .\" Some of the stuff in this file is a bit contorted, because it's also
  29. .\" the regression-test input.
  30. .nr ES 5n
  31. .de ES
  32. .PP
  33. .in +\\n(ESu
  34. .nf
  35. ..
  36. .de EE
  37. .in -\\n(ESu
  38. .fi
  39. .PP
  40. ..
  41. .de PT
  42. .ie \\n(.$>1 .TP "\\$2"
  43. .el .TP
  44. .ie !'\\$1'' \\$1
  45. .el \(bu
  46. ..
  47. .ds Nr \fInroff\fR
  48. .TH CAWF 1 "Version 4.08, August 7, 1995"
  49. .BY CAWF
  50. .SH NAME
  51. cawf \- C version of the nroff-like, Amazingly Workable (text) Formatter
  52. .SH SYNOPSIS
  53. .B cawf
  54. [
  55. .BI \-c " config"
  56. ] [
  57. .BI \-d " device"
  58. ] [
  59. .B \-e
  60. ] [
  61. .BI \-f " font"
  62. ] [
  63. .B \-h
  64. ] [
  65. .BI \-m acros
  66. ] [
  67. .BI \-n " num"
  68. ] [
  69. .BI \-o " pages"
  70. ] [ file ... ]
  71. .SH DESCRIPTION
  72. .if t .tm OOPS -- CAWF THINKS IT'S TROFF!!!
  73. .I Cawf
  74. formats the text from the input \fIfile\fR(s)
  75. (standard input if none)
  76. in an approximation of \*(Nr.
  77. It comes closest to duplicating \*(Nr's
  78. .B man
  79. or
  80. .B ms
  81. macro package styles.
  82. It has some limited support for \*(Nr's
  83. .B me
  84. macros.
  85. .SH OPTIONS
  86. Options must precede file names.
  87. .TP
  88. .BI \-c " config"
  89. defines an alternate path to the device configuration file.
  90. Normally the device configuration file is found in
  91. .I device.cf
  92. in the
  93. .I cawf
  94. library (see the
  95. .B FILES
  96. section).
  97. .IP
  98. The device configuration file contains device character strings for
  99. selecting fonts and the bold or italic type faces.
  100. See the
  101. .B DEVICES
  102. section for more information.
  103. .TP
  104. .BI \-d " device"
  105. specifies the name of the output device.
  106. There are three built\-in devices \- ANSI, NONE and NORMAL \- and
  107. other devices may be defined in the device configuration file.
  108. See the
  109. .B DEVICES
  110. section for more information.
  111. .IP
  112. The NORMAL device is the default.
  113. .TP
  114. .B \-e
  115. directs
  116. .I cawf
  117. to issue an eject (FF or ^L) after the last page.
  118. .TP
  119. .BI \-f " font"
  120. specifies the one font for the device, declared with the
  121. .BI \-d device
  122. option, that is to be used for the
  123. entire document.
  124. .I Font
  125. must match a font associated with the device's stanza in the device
  126. configuration file.
  127. See the
  128. .B DEVICES
  129. section for more information.
  130. .IP
  131. No
  132. .I font
  133. may be specified for the built\-in devices ANSI, NONE or NORMAL.
  134. .TP
  135. .B \-h
  136. requests a help display.
  137. .TP
  138. .BI \-m acro
  139. specifies the macro file to be used.
  140. The standard
  141. .I cawf
  142. distribution supplies macro files to support ``\-man'', ``\-me'' or ``\-ms''.
  143. .I Cawf
  144. finds a macro file by constructing its name from `m',
  145. .I acro
  146. and
  147. .B .mac
  148. \- e. g.,
  149. .BI \-m an
  150. is converted to
  151. .BR man.mac .
  152. The default directory for macro files is defined when
  153. .I cawf
  154. is compiled; it's \fIC:\\SYS\\LIB\\CAWF\fP in the MS\-DOS environment;
  155. .I /Homes/abe/lib/cawf
  156. in the UNIX environment.
  157. .TP
  158. .BI \-n " num"
  159. specifies that the starting page number should be \fInum\fP.
  160. .TP
  161. .BI \-o " pages"
  162. specifies pages and a range of pages to be printed in a comma
  163. separated list.
  164. Ranges are specified in the form ``first-last''.
  165. If the first number of a range is omitted, it is assumed to be one.
  166. If the last number is omitted, it is assumed to be the last page of
  167. the document.
  168. For example, ``-5,9,6,11-'' specifies the printing of pages one
  169. through five, six, nine, and eleven through the end of the document.
  170. .TP
  171. file ...
  172. are the names of files containing \*(Nr source text.
  173. .SH NROFF COMPATIBILITY
  174. .I Cawf
  175. accepts the following raw \*(Nr requests:
  176. .LP
  177.     .\e"    .ad    .bp    .br    .ce    .de    .di    .ds
  178.     .el    .fi    .fl    .ft    .i0    .ie    .if    .in
  179.     .it    .lg    .li    .ll    .ls    .lt    .na    .ne
  180.     .nf    .nr    .ns    .pl    .po    .ps    .rm    .rn
  181.     .rr    .rs    .so    .sp    .ta    .ti    .tl    .tm
  182.     .tr
  183. .LP
  184. and the following in-text codes:
  185. .ES
  186. \e$    \e%    \e*    \e"    \ec    \ef    \eh    \ek
  187. \en    \es    \ew
  188. .EE
  189. plus the full list of \*(Nr/\c
  190. .I troff
  191. special characters in
  192. the original V7 \fItroff\fR manual.
  193. .PP
  194. Many restrictions are present; the behavior in general is a subset of
  195. \*(Nr's.  Of particular note are the following:
  196. .IP \(bu 2
  197. The fully supported nroff request control character is the period.
  198. There is limited support for the  non\-break, acute accent control
  199. character.
  200. .PT
  201. Point sizes do not exist;
  202. .B .ps
  203. is ignored.
  204. .PT
  205. Special vertical spacing \- the
  206. .B .vs
  207. request included \- is ignored.
  208. .PT
  209. Conditionals cover only the numeric comparisons >, =, <, >= and <= on
  210. .BR \en(.$ ;
  211. string com\%par\%isons between a macro parameter and a literal;
  212. .B n
  213. (always true);
  214. and
  215. .BR t
  216. (always false).
  217. Only single line input is accepted from conditionals;
  218. multi\-line input \- e.g., \\(\fIanything\fP\\) \- is not supported.
  219. .PT
  220. The handling of strings is generally primitive.
  221. .PT
  222. The handling of page header and footer strings is limited.
  223. Some in\-text code forms are supported.
  224. When the
  225. .B ms
  226. macros are in use, the
  227. .B CH
  228. and
  229. .B CF
  230. strings are preset to standard
  231. values.
  232. (See the
  233. .B "MS MACROS
  234. and
  235. .B "HEADERS AND FOOTERS
  236. sections for more detail.)
  237. .IP \(bu
  238. Horizontal motion via
  239. .B \eh
  240. must be supplied with a number register interpolation and must be
  241. positive - e. g.,
  242. .BR \eh\en(NN ,
  243. where the value in NN is >= 0.
  244. .IP \(bu
  245. The
  246. .B \ek
  247. function is reliable only after TAB characters, so it is useful only
  248. for measuring table positions.
  249. .IP \(bu
  250. The
  251. .B .di
  252. request only turns output on and off \- any macro name is ignored.
  253. .IP \(bu
  254. Expressions - e. g.,
  255. .B .sp
  256. - are reasonably general, but the
  257. .BR | ,
  258. .BR & ,
  259. and
  260. .BR :\&
  261. operators do not exist, there must be white space between the end of the \*(Nr
  262. function and the beginning of the expression, and 
  263. .B \ew
  264. requires that quote (') be used as the delimiters.
  265. .B \ew
  266. counts the characters inside the quotes and scales the result in ens,
  267. so that, for example, \ew'\e(bu' equals 4n, and \ew'\e(bu'/1n equals 4.
  268. .PT
  269. The only acceptable count for the
  270. .B .it
  271. request is one,
  272. and it is effective only with
  273. .BR man ,
  274. .B me
  275. or
  276. .B ms
  277. macros.
  278. .PT
  279. The default scaling factor is `v' for the
  280. .BR .ne ,
  281. .BR .sp ,
  282. and
  283. .B .pl
  284. raw \*(Nr requests; it is `u' for
  285. .BR .nr ;
  286. and `n' for
  287. .BR .in ,
  288. .BR .ll ,
  289. .BR .ls ,
  290. .BR .lt ,
  291. .BR .po ,
  292. .BR .ta
  293. and
  294. .BR .ti .
  295. (A different scaling factor may be specified with a trailing character.)
  296. .PT
  297. Some obsolete or meaningless requests \-
  298. .BR .i0 ,
  299. .B .lg
  300. and
  301. .B .li
  302. \&\- are silently ignored.
  303. .PT
  304. White space at the beginning of lines,
  305. and embedded white space within lines is dealt with properly.
  306. .PT
  307. Sentence terminators at ends of lines are understood to imply
  308. extra space afterward in filled lines.
  309. .PT
  310. Tabs are im\%plemented crudely and not exactly, although
  311. usually they work as expected.
  312. .PT
  313. Hyphenation is done only at explicit hyphens (`-' characters), em-dashes
  314. (the \\*(em string) and \*(Nr discretionary hyphens.
  315. .IP
  316. The `-' character is always considered a hyphen when it is part of a word, and
  317. is output in the Roman face, no matter what face is in effect for the word.
  318. One or two `-' characters, preceded by a word break, will be output in the
  319. effective face, so the
  320. .B me
  321. \&\\*- string will be output properly, if used as in ``word \\*-''.
  322. .IP
  323. If there are more than two consecutive `-' characters, and the effective
  324. face is bold or italic, only the first two will be output in the effective
  325. face; the remaining `-' characters will be output in the Roman face.
  326. .PT
  327. By default bold and italic characters are emulated with backspacing and
  328. overprinting, but the
  329. .B \-d
  330. and
  331. .B \-f
  332. options, combined with the contents of the device configuration file,
  333. may be used to generate special codes for bold and italic characters.
  334. (See the
  335. .B DEVICES
  336. section for more information.)
  337. .SH "MAN MACROS"
  338. The
  339. .B man
  340. macro set replicates the full V7 manual macros,
  341. plus a few semi-random oddballs.
  342. The full list is:
  343. .ES
  344. \&.AT    .B    .BI    .BR    .BY    .DE    .DS    .DT    .HP    .I
  345. \&.IB    .IP    .IR    .IX    .LP    .NB    .P    .PD    .PP    .RB
  346. \&.RE    .RI    .RS    .SH    .SM    .SS    .TH    .TP    .UC
  347. .EE
  348. .B .BY
  349. and
  350. .B .NB
  351. each take a single string argument (respectively, an indi\%cation of
  352. authorship and a note about the status of the manual page) and arrange
  353. to place it in the page footer.
  354. .B .AT
  355. and
  356. .B .IX
  357. do nothing.
  358. .SH "ME MACROS"
  359. The
  360. .B me
  361. macro subset has been derived from the
  362. .I cawf
  363. .B ms
  364. macros by Chet Creider <creider@csd.uwo.ca>.
  365. It includes:
  366. .ES
  367. \&.(l    .(q    .)l    .)q    .b    .bu    .i    .ip    .lp    .np
  368. \&.pp    .r    .sh    .sm    .u    .uh
  369. .EE
  370. The
  371. .B .(l
  372. macro supports the C and L options.
  373. Size changes via the
  374. .B .sz
  375. and
  376. .B .sm
  377. macros are silently ignored.
  378. The
  379. .B .u
  380. macro just prints its argument in italics.
  381. The
  382. .B ps
  383. and
  384. .B pi 
  385. number registers exist and can be changed.
  386. The
  387. .B td
  388. string is available and is preset to today's date.
  389. Single spacing is not enforced in lists and quotations.
  390. .PP
  391. The
  392. .BR .AB ,
  393. .BR .AE ,
  394. .BR .AI ,
  395. .BR .AU ,
  396. .BR .DA ,
  397. .BR .ND ,
  398. .BR .TL
  399. and
  400. .B .UX
  401. macros have been retained from the
  402. .B ms
  403. set.
  404. The
  405. .B .XP
  406. macro has been borrowed from the Berkeley additions to the
  407. .B ms
  408. macro set.
  409. .SH "MS MACROS"
  410. The
  411. .B ms
  412. macro set is a substantial subset of the V7 manuscript macros.
  413. The macros are:
  414. .ES
  415. \&.AB    .AE    .AI    .AU    .B    .CD    .DA    .DE    .DS    .I
  416. \&.ID    .IP    .LD    .LG    .LP    .ND    .NH    .NL    .PP    .QE
  417. \&.QP    .QS    .R    .RE    .RP    .RS    .SH    .SM    .TL    .TP
  418. \&.UL    .UX
  419. .EE
  420. Size changes are recognized but ignored, as are
  421. .B .RP
  422. and
  423. .BR .ND .
  424. .B .UL
  425. just prints its argument in italics.
  426. .BR .DS / .DE
  427. does not do a keep,
  428. nor do any of the other macros that normally imply keeps.
  429. .PP
  430. The
  431. .B DY
  432. string is available, is preset to today's date, and
  433. may be altered with the
  434. .B .DA
  435. macro.
  436. The
  437. .BR PD ,
  438. .BR PI ,
  439. and
  440. .BR LL
  441. number registers exist and can be changed.
  442. .PP
  443. The
  444. .B CH
  445. string is preset for page numbering, and the
  446. .B CF
  447. string is preset to the contents of the
  448. .B DY
  449. string.
  450. (The
  451. .B DY
  452. string can be set with the
  453. .B .DA
  454. macro; it is preset to today's date.)
  455. .SH "HEADERS AND FOOTERS"
  456. .I Cawf's
  457. page header and footer handling is limited.
  458. It comes closest to that of the
  459. .B ms
  460. macros with the following characteristics.
  461. .IP \(bu 2
  462. Strings may be placed in three areas \- the left, center, and right
  463. portions of page header and footer lines.
  464. .PT
  465. The page header line is not normally printed on the first page of
  466. output, but may be selected with the ``.^b fh 1'' directive.
  467. .PT
  468. The ``.^b lf n'' and ``.^b lh n'' directives may be used to specify
  469. the number of lines in the page header and footer sections.
  470. .IP
  471. The default section length is five lines \- two blank lines, followed
  472. by the header or footer line, followed by two blank lines.
  473. .IP
  474. However, the last blank footer line is suppressed, so that printers
  475. that can't look ahead to a following form feed won't issue an extra
  476. form feed and cause a fully blank page to be printed.
  477. This makes the effective default footer section length four lines \-
  478. five minus one.
  479. .PT
  480. The ``\\f'' (font change) in\-text code is interpreted.
  481. Each of the three areas on the header or footer line is a separate
  482. entity with respect to type faces.
  483. Each begins in the Roman face and
  484. .I cawf
  485. closes it by returning to the Roman face, if necessary.
  486. .PT
  487. The ``\\n'' (number register interpolation) and ``\\*'' (string
  488. interpolation) in\-text codes are expanded.
  489. .PT
  490. The `%' current page number in\-text code is interpreted.
  491. Use the ``\\%'' two character sequence to introduce a percent
  492. sign into a header or footer area.
  493. .PT
  494. Any other two character sequence, beginning with `\\', is contracted
  495. into the second character of the sequence \- e.g., ``\\\\'' becomes
  496. a single `\\' character.
  497. .PT
  498. In\-text codes within strings are not interpreted \- e.g., when a
  499. string contains a request to interpolate a second string or change
  500. font, the in\-text code is printed, not its interpretation.
  501. .PP
  502. When the
  503. .B ms
  504. macros are in use, the
  505. .B CH
  506. string is preset for page numbering, and the
  507. .B CF
  508. string is preset to the contents of the
  509. .B DY
  510. string (today's date).
  511. (See the
  512. .B "MS MACROS
  513. section.)
  514. .PP
  515. Text is is placed in the page header and footer lines from the
  516. .BR LH ,
  517. .BR CH ,
  518. .BR RF ,
  519. .BR LF ,
  520. .BR CF ,
  521. and
  522. .B RF
  523. strings.
  524. The
  525. .B .^b
  526. requests provide limited control over the printing of the page header
  527. and footer lines:
  528. .LP
  529. .ta \w'.^b HF 0'u+3n
  530. .nf
  531. \&.^b fh 1    enables header string printing on the first page
  532. \&.^b fh 0    disables header string printing on the first page
  533. \&.^b HF 1    enables header/footer string printing
  534. \&.^b HF 0    disables header/footer string printing
  535. \&.^b lf \fIn\fP    print an (\fIn\fP - 1) line page footer (default \fIn\fP is 5)
  536. \&.^b lh \fIn\fP    print an \fIn\fP line page header (default \fIn\fP is 5)
  537. .fi
  538. .LP
  539. There are appropriate
  540. .B .^b
  541. requests in the distribution
  542. .BR man ,
  543. .B me
  544. and
  545. .B ms
  546. macro files.
  547. (The
  548. .B me
  549. and
  550. .B ms
  551. macro files use another
  552. .B .^b
  553. request, \fB.^b NH\fP, to enable numbered section header processing.)
  554. .SH OUTPUT
  555. The default output format supported by
  556. .IR cawf ,
  557. in its distributed form,
  558. is that appropriate to a dumb terminal,
  559. using overprinting for italics (via underlining) and bold.
  560. The \*(Nr special characters are printed as some vague approximation
  561. (it's sometimes extremely vague) to their correct appearance.
  562. .PP
  563. One part of
  564. .IR cawf 's
  565. knowledge of the output device, related to the formation of characters,
  566. is established by a device file, which is read before the user's input.
  567. The search for it begins in
  568. .IR cawf 's
  569. library directory, under the name \fIterm\fP.\fBdev\fP
  570. (where \fIterm\fR is the value of the TERM environment variable).
  571. Failing to find that,
  572. .I cawf
  573. searches for
  574. .BR dumb.dev .
  575. (See the
  576. .B FILES
  577. section for a description of the path to
  578. .IR cawf 's
  579. library directory.)
  580. The device file
  581. uses special internal requests
  582. to set up resolution, special characters 
  583. and more normal \*(Nr functions to set up page length, etc.
  584. .PP
  585. .I Cawf
  586. has limited support for special forms of bold and italic characters.
  587. It is provided through the
  588. .B \-c
  589. .IR config ,
  590. .BI \-d device
  591. and
  592. .BI \-f font
  593. options.
  594. See the
  595. .B DEVICES
  596. section for more information.
  597. .PP
  598. Note the distinction between the device and the output device configuration
  599. files.
  600. The device file typically defines characters and constant output parameters.
  601. The output device configuration file defines font and type face codes.
  602. It is usually not necessary to define a separate device file for each
  603. device represented in the output device configuration file \- the
  604. .I dumb.dev
  605. device file will suffice for almost all representations.
  606. .SH DEVICES
  607. .I Cawf
  608. supports primitive output device configuration for font and type face
  609. control.
  610. One font may be selected for the entire document by directing
  611. .I cawf
  612. to issue a font selection control character string at the beginning
  613. of the document, and control character strings may be selected for
  614. switching between the bold, italic and Roman type faces.
  615. .PP
  616. The
  617. .B \-c
  618. .IR config,
  619. .BI \-d device
  620. and
  621. .BI \-f font
  622. options direct the font and type face selections.
  623. .PP
  624. The
  625. .BI \-d device
  626. option specifies the name of the device.
  627. .I Cawf
  628. has three built\-in devices \- ANSI, NONE and NORMAL.
  629. When the ANSI device is selected,
  630. .I cawf
  631. issues the ANSI shadow mode control codes, ``ESC [ 7 m'', to represent
  632. the bold face;
  633. the ANSI underscore control codes, ``ESC [ 4 m'', to represent the italic
  634. face;
  635. and the ANSI control codes, ``ESC [ 0 m'', to represent the ROMAN face.
  636. No
  637. .BI \-f font
  638. specification is permitted with the ANSI device.
  639. .PP
  640. When the NONE device is selected,
  641. .I cawf
  642. uses no special output codes to represent the type faces.
  643. No
  644. .BI \-f font
  645. specification is permitted with the ANSI device.
  646. .PP
  647. The NORMAL output device is the default.
  648. When it's selected,
  649. .I cawf
  650. overprints each bold character two times, using three issuances of each
  651. bold character, separated by backspace characters;
  652. it issues an underscore and backspace before each italic character.
  653. No
  654. .BI \-f font
  655. specification is permitted with the ANSI device.
  656. The
  657. .IR bsfilt (1)
  658. filter may be used to further process the backspace codes output for
  659. a NORMAL device.
  660. .PP
  661. All other devices named in the
  662. .BI \-d device
  663. option must be represented by a stanza in the device configuration file.
  664. The device configuration file is usually contained in
  665. .I device.cf
  666. in
  667. .IR cawf's
  668. library directory (see the
  669. .B FILES
  670. section for more information).
  671. An alternate device configuration file path may be specified with the
  672. .BI \-c config
  673. option.
  674. .PP
  675. The
  676. .B DEVICE CONFIGURATION FILE
  677. section describes the organization of the device configuration file.
  678. It is easy to add devices to the
  679. .I device.cf
  680. supplied in the
  681. .I cawf
  682. distribution.
  683. .PP
  684. The
  685. .BI \-f font
  686. option may be used with the
  687. .BI \-d device
  688. option, when the appropriate stanza in the device configuration file
  689. contains an entry for the named
  690. .IR font .
  691. The
  692. .B DEVICE CONFIGURATION FILE
  693. section describes how fonts are defined in device configuration file
  694. stanzas.
  695. .SH DEVICE CONFIGURATION FILE
  696. The device configuration file defines the special character codes
  697. necessary to direct output devices to select fonts and to produce
  698. bold, italic and Roman type faces.
  699. .PP
  700. The configuration file is usually found in
  701. .I device.cf
  702. in
  703. .IR cawf 's
  704. library directory (see the
  705. .B FILES
  706. section for more information).
  707. It is organized into two main parts \- comments and device stanzas.
  708. Comments are any lines that begin with the pound sign (`#') character.
  709. They are informational only and
  710. .I cawf
  711. ignores them.
  712. .I Cawf
  713. also ignores empty lines, so they may be used as vertical white space.
  714. .PP
  715. Stanzas name devices and define their font and type face control strings.
  716. A stanza begins with the name of the device, starting at the beginning
  717. of a line and occupying the entire line.
  718. The body of the stanza, defining fonts and type faces, is formed of
  719. lines beginning with white space (a TAB or space characters) that
  720. directly follow the device name.
  721. .PP
  722. Individual lines of the stanza body contain a key character, followed
  723. by a equal sign, followed by the font name (if a font key) and the
  724. output device control codes.
  725. .I Cawf
  726. issues the font control codes once, at the beginning of output, so
  727. only one font may be selected.
  728. The type face control codes are issued at each change of type face.
  729. .PP
  730. The key characters are:
  731. .ne 4
  732. .DS
  733. b    for bold
  734. f    for font definition
  735. i    for italic
  736. r    for Roman
  737. .DE
  738. The `b', `i' and `r' key codes are followed by an equal sign (`=') and
  739. their control code definition.
  740. The `f' key code is followed by an equal sign (`='), the font name,
  741. another equal sign and the font control code definition.
  742. .PP
  743. Control code definitions may contain any printable ASCII characters.
  744. Non\-printable characters may be encoded in octal notation with the `\\nnn'
  745. form or in hexadecimal with the `\\xnn' form.
  746. The special code, `\\E' (or `\\e') represents the ESC control
  747. character (\\033 or \\x1b).
  748. .PP
  749. Here's a sample showing the definition for the HP LaserJet III.
  750. The stanza name is ``lj3''.
  751. All its non\-printable characters are ESCs; the first is coded in
  752. octal form; the second with '\\E'; the rest, in hexadecimal form.
  753. TAB is used as the leading white space character for the stanza
  754. body lines.
  755. .DS
  756. # HP LaserJet III
  757.  
  758. lj3
  759.         b=\\033(s7B
  760.         i=\\E(s1S
  761.         r=\\x1b(s0B\\x1b(s0S
  762.         f=c10=\\x1b&l0O\\x1b(8U\\x1b(s0p12h10v0s0b3T
  763.         f=c12ibm=\\x1b&l0O\\x1b(10U\\x1b(s0p10.00h12.0v0s0b3T
  764.         f=lg12=\\x1b&l0O\\x1b(8U\\x1b(s12h12v0s0b6T
  765. .DE
  766. .PP
  767. The distribution
  768. .I device.cf
  769. file defines the following devices and fonts.
  770. .LP
  771. .ta \w'kxp1180'u+3n +\w'Italic:'u+3n +\w'bps10'u+6n
  772. .nf
  773. .ne 3
  774. epson    dot matrix printer in Epson FX-86e/FX-800 mode
  775.     Bold:    Double-strike
  776.     Fonts:    none
  777.  
  778. .ne 4
  779. ibmppds    IBM Personal Printer Data Stream (PPDS) protocol
  780.     Bold:    Double-strike
  781.     Italic:    Underline
  782.     Fonts:    none
  783.  
  784. .ne 12
  785. kxp1124    Panasonic KX\-P1124 dot matrix printer in PGM mode
  786.     Bold:    Emphasized
  787.     Fonts:    c10    10 Characters Per Inch (CPI) Courier
  788.         c12    12 CPI Courier
  789.         bps10    10 CPI Bold PS
  790.         bps12    12 CPI Bold PS
  791.         p10    10 CPI Prestige
  792.         p12    12 CPI Prestige
  793.         s10    10 CPI Script
  794.         s12    12 CPI Script
  795.         ss10    10 CPI Sans Serif
  796.         ss12    12 CPI Sans Serif
  797.  
  798. .ne 10
  799. kxp1180    Panasonic KX\-P1180 dot matrix printer in PGM mode
  800.     Bold:    Emphasized
  801.     Fonts:    c10    10 Characters Per Inch (CPI) Courier
  802.         c12    12 CPI Courier
  803.         bps10    10 CPI Bold PS
  804.         bps12    12 CPI Bold PS
  805.         p10    10 CPI Prestige
  806.         p12    12 CPI Prestige
  807.         ss10    10 CPI Sans Serif
  808.         ss12    12 CPI Sans Serif
  809.  
  810. .ne 6
  811. lj3    HP LaserJet III
  812.     Fonts:    c10    10 point, 12 Characters Per Inch (CPI)
  813.             Courier
  814.         c12ibm    12 point, 10 CPI Courier, IBM\-PC
  815.             Symbol Set
  816.         lg12    12 point, 12 CPI Letter Gothic
  817.  
  818. .ne 4
  819. vgamono    VGA monochrome monitor for MS\-DOS
  820.     (ANSI.SYS driver required for MS\-DOS)
  821.     Italic:    Reverse-video
  822.     Fonts:    none
  823. .SH FILES
  824. .I Cawf
  825. resource files are located in the
  826. .I cawf
  827. library directory \- \fIC:\\SYS\\LIB\\CAWF\fP, the MS\-DOS environment
  828. default;
  829. or
  830. .IR /Homes/abe/lib/cawf ,
  831. the UNIX environment default.
  832. These defaults can be overridden by the CAWFLIB environment variable,
  833. or changed in the cawflib.h header file.
  834.  
  835. .ta \w'device.cf'u+3n
  836. .nf
  837. common    common device-independent initialization
  838. device.cf    output device configurations
  839. *.dev    device-specific initialization
  840. m*.mac    macro package files
  841. .SH DIAGNOSTICS
  842. Unlike
  843. .IR nroff ,
  844. .I cawf
  845. complains whenever it sees unknown requests.
  846. All diagnostics appear on the standard error file.
  847. .ad
  848. .SH HISTORY
  849. Vic Abell of Purdue University <abe@cc.purdue.edu> derived
  850. .I cawf
  851. from
  852. .IR awf ,
  853. \&``the Amazingly Workable (text) Formatter,'' 
  854. written by Henry Spencer of the University of Toronto.
  855. The Toronto work was a supplement to the C News project.
  856. The Purdue effort was aimed at producing a C language version that
  857. would run on small systems, particularly MS\-DOS ones.
  858. The adaptation of the
  859. .B me
  860. macros was done by Chet Creider <creider@csd.uwo.ca>.
  861. Chet also contributed ideas for device, font and type face support.
  862. .PP
  863. The MS\-DOS version of
  864. .I cawf
  865. has been compiled with version 3.1 of Borland's C++ compiler.
  866. It runs under the Mortis Kern Systems Toolkit KornShell,
  867. .IR ksh (1),
  868. and COMMAND.COM.
  869. .I Cawf
  870. has also been ported to OS/2 1.x and OS/2 2.x, using the Microsoft C
  871. and EMX GNU C compilers.
  872. .SH BUGS
  873. Nroff and troff mavens will have many complaints.
  874. Some may even represent bugs and not deliberate omissions.
  875. .PP
  876. Watch out for scaling factors - especially on requests like
  877. .BR \ew .
  878. .PP
  879. The overprinting required to create bold and italicized characters is
  880. tiresome on a slow printer.
  881. The
  882. .IR bsfilt (1)
  883. post\-filter from this distribution may be used to alleviate that
  884. nuisance by managing the backspacing codes from
  885. .IR cawf 's
  886. NORMAL device output.
  887. .PP
  888. The printing of bold and italic characters is sometimes better handled by
  889. special printer codes.
  890. Use
  891. .IR cawf 's
  892. .B \-c
  893. .IR config ,
  894. .BI \-d device
  895. and
  896. .BI \-f font
  897. options to produce special font and device output control codes.
  898. .PP
  899. .I Cawf
  900. has a small amount of built-in code for the 
  901. .BR man ,
  902. .B me
  903. and
  904. .B ms
  905. macro packages, but none for any others.
  906. .PP
  907. The stacking for the
  908. .B .so
  909. request is limited.
  910. .SH SEE ALSO
  911. bsfilt(1),
  912. colcrt(1),
  913. man(7),
  914. me(7),
  915. ms(7)
  916. and
  917. nroff(1).
  918.